$OpenBSD: README,v 1.18 2015/07/18 20:33:07 ajacoutot Exp $

+-----------------------------------------------------------------------
| Running ${FULLPKGNAME} on OpenBSD
+-----------------------------------------------------------------------

The Puppet Dashboard has been installed into ${INSTDIR}

Configuration is done in:
    ${INSTDIR}/config/settings.yml

Database Configuration
======================

Before starting the Dashboard, a MariaDB database must be configured in:
    ${INSTDIR}/config/database.yml

The following commands can be used to create the database:
    # mysql -uroot -p<password>
    MariaDB [(none)]> CREATE DATABASE dashboard_production CHARACTER SET utf8;
    MariaDB [(none)]> CREATE USER 'dashboard'@'localhost' IDENTIFIED BY 'my_password';
    MariaDB [(none)]> GRANT ALL PRIVILEGES ON dashboard_production.* TO 'dashboard'@'localhost';
    MariaDB [(none)]> EXIT

The MariaDB maximum packet size needs to be increased to permit larger
rows in the database; ${SYSCONFDIR}/my.cnf must be edited to include:
max_allowed_packet = 32M
Then the server must be restarted by running:
    # ${RCDIR}/mysqld restart

Once the database has been setup and MariaDB is up and running, the
following command must be run to create the tables:
    # cd ${INSTDIR} && su -m _puppet-dashboard -c \
        "LD_PRELOAD=libpthread.so rake${MODRUBY_BINREV} RAILS_ENV=production db:migrate"

Puppet Configuration
====================

By default, Puppet Dashboard will start a Rails server on port 3000.

To use the Dashboard for reports, all agent nodes must submit reports to
the master and the master must send reports to the Dashboard.
${SYSCONFDIR}/puppet/puppet.conf needs to be edited accordingly:
[agent]
    report = true # this is the default
[master]
    reports = store, http
    reporturl = http://dashboard.domain.tld:3000/reports/upload

Node Classification
-------------------
To use the Dashboard external node classifier (ENC) alongside Puppet DSL
node definitions, the master should contain the following lines (to be
adapted accordingly):
[master]
    node_terminus = exec
    external_nodes = /usr/bin/env PUPPET_DASHBOARD_URL=http://localhost:3000 ${INSTDIR}/bin/external_node

Maintenance
===========

To import old Puppet reports that were created before the Dashboard got
installed, the following command can be used:
    # cd ${INSTDIR} && su -m _puppet-dashboard -c \
        "LD_PRELOAD=libpthread.so rake${MODRUBY_BINREV} RAILS_ENV=production reports:import"

Note: For the above command to work, the _puppet-dashboard user must
be a member of the _puppet group.

Cron Jobs
---------
The MariaDB database should be optimized on a montly basis. This can be
done by adding the following entry to the root's crontab(5):
0	0	1	*	*	cd ${INSTDIR} && su -m _puppet-dashboard -c "LD_PRELOAD=libpthread.so ${LOCALBASE}/bin/rake${MODRUBY_BINREV} RAILS_ENV=production db:raw:optimize"

Over time, old reports will start to accumulate which can slow down the
Dashboard. Adding the following line to the root's crontab(5) will clean
up reports older than 1 month and will run every night:
0	0	*	*	*	cd ${INSTDIR} && su -m _puppet-dashboard -c "LD_PRELOAD=libpthread.so ${LOCALBASE}/bin/rake${MODRUBY_BINREV} RAILS_ENV=production reports:prune upto=1 unit=mon"

Upgrade
-------
After updating the Dashboard to a new release, the following command
needs to be run to update database schemas:
    # cd ${INSTDIR} && su -m _puppet-dashboard -c \
        "LD_PRELOAD=libpthread.so rake${MODRUBY_BINREV} RAILS_ENV=production db:migrate"

Phusion Passenger Integration (i.e. mod_rails)
==============================================

The WEBrick server script provided by Puppet Dashboard is not fit for
production. For better performance, it is advised to run the Dashboard
under Passenger along with a compatible web server.

e.g. with nginx
---------------
The nginx(8) package provides a FLAVOR for passenger support which the
version in the base system doesn't, so it must be installed first:
    # pkg_add ruby-passenger nginx--passenger

Next, ${SYSCONFDIR}/nginx/nginx.conf needs to be modified with the
following requirements as a start:

* http{} block
    passenger_root ${LOCALBASE}/lib/phusion-passenger;
    passenger_ruby ${RUBY};

Note that the output of `passenger-config --root` will give the
"passenger_root" value.

* server{} block
        listen       3000;
        root         ${INSTDIR}/public;
        passenger_enabled on;

The nginx(8) daemon installed from packages(7) is started by the
"enginx" rc.d(8) script and obviously puppet_dashboard must be
disabled (the workers must be enabled though).
Here's a sample rc.conf.local(8) extract:
pkg_scripts=enginx puppet_dashboard_workers

Going further
=============

Setting up followings is out of the scope of this README but should be
considered when running Puppet Dashboard in production.
- authentication (by default, anyone can access the Dashboard)
- https (for encrypted communication)

More information is available at:
    http://docs.puppetlabs.com/dashboard/manual/1.2/index.html
